home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / fmodla13.zip / FMODULA2.DOC < prev    next >
Text File  |  1992-01-29  |  82KB  |  2,839 lines

  1.  
  2.  
  3.                           Modula-2 Compiler Version 1.3
  4.  
  5.                  (C) Copyright 1987,1988 Fitted Software Tools.
  6.                               All rights reserved.
  7.  
  8.  
  9.                               Fitted Software Tools
  10.                                  P.O.Box 867403
  11.                                  Plano, TX 75086
  12.                                 BBS 214/517-4629
  13.  
  14.  
  15.  
  16.  
  17.      
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                              DISCLAIMER OF WARRANTY
  29.  
  30.      THIS SOFTWARE AND MANUAL ARE PROVIDED "AS IS" AND WITHOUT WARRANTIES
  31.      AS TO PERFORMANCE OR MERCHANTABILITY.
  32.  
  33.      THIS SOFTWARE IS PROVIDED WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES
  34.      WHATSOEVER. BECAUSE OF THE DIVERSITY OF CONDITIONS AND HARDWARE UNDER
  35.      WHICH THIS SOFTWARE MAY BE USED, NO WARRANTY OF FITNESS FOR A
  36.      PARTICULAR PURPOSE IS OFFERED. THE USER IS ADVISED TO TEST THIS
  37.      SOFTWARE THOROUGHLY BEFORE RELYING ON IT. THE USER MUST ASSUME THE
  38.      ENTIRE RISK OF USING THIS SOFTWARE.
  39.  
  40.      
  41.  
  42.      All the information in this document is believed to be correct at the
  43.      time of publishing.  We do, however, reserve the right to make any
  44.      changes in product specifications and/or availability without notice. 
  45.  
  46.      
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.      IBM is a registered trademark of International Business Machines
  57.      Corporation.
  58.  
  59.      
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.      Introduction                                                         2
  68.      
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                                     Chapter 1
  77.  
  78.                                   Introduction
  79.  
  80.  
  81.  
  82.      Thank you for your interest in our Modula-2 compiler. 
  83.  
  84.      This system features a Modula-2 compiler with an integrated editor and
  85.      "make" facility, a program linker, a makefile generator, and an
  86.      execution profiler. 
  87.  
  88.      The compiler generates code for the Intel 8086 "huge" or "large"
  89.      memory model: In the "huge" memory model, each module has its own data
  90.      and code segment, each of which can be up to 64k in size; In the
  91.      "large" memory model, all the modules' static data is combined into a
  92.      single data segment.  In either model, pointers are 4 bytes long and
  93.      all the leftover memory is available for the "heap". More restrictive
  94.      memory models are not currently supported. 
  95.  
  96.      All the library and runtime support source code is provided to our
  97.      registered users (see Shareware).
  98.  
  99.      We hope that our effort will prove itself worthy of your support. 
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.      Introduction                                                         3
  134.      
  135.  
  136.  
  137.  
  138.  
  139.  
  140.      1.1 Hardware requirements
  141.  
  142.  
  143.      This system will run on IBM PC, PC/AT, or compatible systems with at
  144.      least 512K of RAM, two double sided floppy disk drives and a
  145.      monochrome display adapter, color graphics adapter or equivalent. 
  146.  
  147.      For best performance, a hard disk and 640K of RAM are recommended. 
  148.  
  149.      
  150.  
  151.  
  152.  
  153.  
  154.      1.2 Software requirements
  155.  
  156.  
  157.      This system will run under DOS version 2.0 or later. 
  158.  
  159.      No other software is required to use this system, but you will need an
  160.      assembler if you intend to modify one of the runtime support modules:
  161.      M2Reals (floating point support), M2Longs (LONG arithmetic) or M2Procs
  162.      (coroutine handling). 
  163.  
  164.      
  165.  
  166.  
  167.  
  168.  
  169.      1.3 Version 1.3
  170.  
  171.  
  172.      We moved.  The version 1.3 distribution files reflect our new
  173.      address. 
  174.  
  175.      
  176.  
  177.  
  178.  
  179.  
  180.      1.4 About version 1.2
  181.  
  182.  
  183.      This release was prompted by our desire to bring maximum performance
  184.      to our users as soon as possible. 
  185.  
  186.      We worked out an agreement with P.M.I. to make available to the users
  187.      of this Modula-2 compiler their Repertoire (R) library.  To help
  188.      migrate this system to our environment, we made some minor changes to
  189.      the compiler. 
  190.  
  191.      To avoid confusion, we decided to up the version number of the system
  192.      to 1.2.
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.      Introduction                                                         4
  200.      
  201.  
  202.  
  203.      This is not really a major product update for us, as the product is
  204.      mostly unchanged from 1.1. We took the opportunity, of course, to fix
  205.      all the known problems with the earlier versions of the system.  While
  206.      adding some additional power into the compiler, we put it on a small
  207.      diet, reducing its size by some precious Ks without impacting its
  208.      performance. 
  209.  
  210.      As 1.2 goes out, we expand our support options by giving our users the
  211.      capability to contact us on BIX. By the time you read this, our
  212.      conference (fst) should be open. 
  213.  
  214.      The main changes in the compiler are:
  215.  
  216.           The CASE statement labels are no longer restricted in range and
  217.           the compiler will generated one of two different code sequences
  218.           depending on the density of the labels within their range.
  219.  
  220.           INC and DEC now accept a LONGCARD or a LONGINT as the first
  221.           argument.
  222.  
  223.           We added the capability to add or subtract a CARDINAL to/from an
  224.           ADDRESS. These operations affect only the offset portion of the
  225.           address!  Similarly, the INC and DEC procedures will also take an
  226.           ADDRESS for the first argument, but operate on its offset portion
  227.           only.  In cases where it cannot be guarateed that the operation
  228.           will not cause an overflow of the offset portion of the address,
  229.           please continue to use the FLAT and PTR procedures. 
  230.           Incidentally, the ALLOCATE procedure of Storage always returns a
  231.           normalized pointer, i.e., the offset will always be less than 16.
  232.  
  233.           SIZE and TSIZE can be imported from SYSTEM; a reference to either
  234.           of these will be translated into a reference to the standard
  235.           procedure SIZE. This was done for compatibility with other
  236.           systems only, and you should not use this capability in any new
  237.           programs.
  238.  
  239.           The standard procedure SIZE now accepts any variable designator
  240.           as its argument.
  241.  
  242.      We recoded the Storage module to make it faster. 
  243.  
  244.      To the Strings module several new procedures were added. 
  245.  
  246.      The compiler and the new libraries will, before invoking DOS, truncate
  247.      any component of a file name that is larger than 8 characters.  We
  248.      found it necessary to do this because at least one network package out
  249.      there could not handle the "illegal" file names.  User programs using
  250.      our libraries for file handling should not have to worry about this. 
  251.  
  252.      
  253.  
  254.  
  255.  
  256.  
  257.      1.5 What was new in version 1.1
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.      Introduction                                                         5
  266.      
  267.  
  268.  
  269.  
  270.      The compiler now allows the specification of module priorities in the
  271.      module header.  As an example on the use this new capability, we
  272.      include the source code of a simple multitasking communications
  273.      program running under a small kernel that supports interrupt
  274.      processes, signals and locks. 
  275.  
  276.      The compiler and linker now allow you to use a "large" memory model. 
  277.      In this memory model, all the modules share a common data segment for
  278.      static data; pointers are still 4 bytes long.  Using the large memory
  279.      model usually produces smaller (and faster, although you may not be
  280.      able to tell) executable files, as data references to external objects
  281.      do not cost anything extra. 
  282.  
  283.      The compiler has new command line options, so that you can directly
  284.      invoke the editor or the make process from the command line. 
  285.  
  286.      From the compiler menu you may now invoke the linker and the makefile
  287.      generator, although these are still freestanding programs. 
  288.  
  289.      The compiler now accepts EXPORT statements in definition modules, but
  290.      simply treats them as comments.  This capability was requested by some
  291.      of our users. 
  292.  
  293.      The editor includes 3 new commands: delete line, delete to end of line
  294.      and delete word. 
  295.  
  296.      M2ED.CFG now has additional information in it: through EDCONFIG you
  297.      may now select the display attributes (colors) to be used by the
  298.      editor; you may also select different default values for tab spacing
  299.      and whether or not to expand tabs. 
  300.  
  301.      A new option was added to M2Link: /SWAP. When invoked, this option
  302.      directs the linker to swap the code segments of the program being
  303.      processed out to disk, thereby allowing you to link larger programs. 
  304.  
  305.      Many new library modules were added: Keyboard, display, DOS file and
  306.      directory handling, and even modules to handle windows and pop up and
  307.      pull down menus.  These libraries are provided just to help you get
  308.      started; We will leave the production of more elaborate libraries to
  309.      those vendors that specialize in such. 
  310.  
  311.      
  312.  
  313.  
  314.  
  315.  
  316.      1.6 As version 1.1 becomes history...
  317.  
  318.  
  319.      Before going on, we would like to thank all our registered users: your
  320.      encouragement made this new version possible.  We will strive to never
  321.      let you down. 
  322.  
  323.      We also appreciated the input received from those that evaluated the
  324.      product and were nice enough to let us in on their thoughts. 
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.      Software installation                                                6
  332.      
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.                                     Chapter 2
  341.  
  342.                               Software installation
  343.  
  344.  
  345.  
  346.      Before starting, please print the file READ.ME, which provides a
  347.      description of every file in the distribution disks. 
  348.  
  349.      
  350.  
  351.  
  352.  
  353.  
  354.      2.1 Theory
  355.  
  356.  
  357.      The library module TermIO (through which Terminal does its IO)
  358.      requires that the ANSI.SYS driver be installed. 
  359.  
  360.      The executable files (MC.EXE, M2LINK.EXE, ...) should, for ease of
  361.      operation, be placed in a drive/directory named in the DOS PATH
  362.      variable. 
  363.  
  364.      The editor configuration file M2ED.CFG must be accessible through the
  365.      DOS PATH variable. 
  366.  
  367.      Both the compiler and the linker will use the environment variable
  368.      M2LIB to locate required library modules (the format for the M2LIB
  369.      entry matches that of the DOS PATH).
  370.  
  371.      The environment variable M2MODEL may be set to 'HUGE' or 'LARGE',
  372.      after which you no longer have to tell the compiler what memory model
  373.      to compile for (unless you wish to override the environment
  374.      selection).  IF M2MODEL is not set, the compiler, by default (and for
  375.      compatibility with version 1.0), assumes that you want to compile for
  376.      the HUGE model. 
  377.  
  378.      The compiler and utilities in this package do not keep many files open
  379.      simultaneously.  If you set the FILES parameter in CONFIG.SYS to 10
  380.      you should not encounter any problems.  For performance
  381.      considerations, you should also allocate more than the default number
  382.      of buffers for DOS: If you are running on a PC class machine, try
  383.      allocating 20 buffers in your CONFIG.SYS. On an AT type machine, try
  384.      64 buffers. 
  385.  
  386.      Example CONFIG.SYS:
  387.  
  388.           DEVICE=ANSI.SYS
  389.           FILES=10
  390.           BUFFERS=20
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.      Software installation                                                7
  398.      
  399.  
  400.  
  401.      This compiler is a memory hog (you heard it here first!).  Therefore,
  402.      unless you have 640k of memory installed in your system, you should
  403.      have COMMAND.COM available for reload once you exit the compiler. 
  404.  
  405.      If you have 640k of memory, you will probably want to enable the
  406.      "COMMAND save" feature of the compiler, which will stop it from
  407.      clobbering the resident portion of COMMAND.COM. Just add the following
  408.      line to your AUTOEXEC.BAT file:
  409.  
  410.           SET CMDSIZE=NN
  411.  
  412.      where NN is the size of the resident portion of COMMAND.COM in K (18
  413.      for DOS 3.0).
  414.  
  415.      MC clobbers the top of the memory space available for use during
  416.      initialization.  Therefore, to find out the size of the resident
  417.      portion of COMMAND.COM try the following procedure: start by setting
  418.      CMDSIZE to the size of COMMAND.COM. If now you execute MC, exit it,
  419.      and press the F3 key, DOS will still remember your MC command. 
  420.      Decrement CMDSIZE and retry the MC test until the system forgets your
  421.      last command (COMMAND.COM had to be reloaded). 
  422.  
  423.      Because the compiler supports 2 different memory models, 2 different
  424.      sets of library object files (.M2O) are provided, one for each of the
  425.      memory models.  If you are going to be using both memory models, keep
  426.      each of these sets of files on a different directory, and change the
  427.      M2LIB path according to the model in use.  We use the following BAT
  428.      files to take care of this:
  429.  
  430.  
  431.      LARGE.BAT:
  432.           set M2MODEL=LARGE
  433.           set M2LIB=C:\M2\LIB;C:\M2\LIBL
  434.  
  435.      HUGE.BAT:
  436.           set M2MODEL=HUGE
  437.           set M2LIB=C:\M2\LIB;C:\M2\LIBH
  438.  
  439.      where \M2\LIB is the directory where all the DEF files reside,
  440.      \M2\LIBL contains the LARGE memory model M2O files,... 
  441.  
  442.      In the following discussion we will, for simplicity sake, assume that
  443.      you will be using only one of the memory models. 
  444.  
  445.      
  446.  
  447.  
  448.  
  449.  
  450.      2.2 Recommended setup for a system with 2 floppy drives
  451.  
  452.  
  453.      This whole system is too large to fit in a single 360k floppy. 
  454.      Therefore, it is recommended that you build a "compiler" floppy and a
  455.      "utilities" floppy (you may combine them both in a 720k or 1.2Mb
  456.      floppy). 
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.      Software installation                                                8
  464.      
  465.  
  466.  
  467.      On the compiler floppy, place the compiler (MC.EXE), all the library
  468.      definition modules (*.DEF), the file M2ED.CFG and DOS' COMMAND.COM.
  469.  
  470.      The utilities floppy will take the rest of the system: the linker
  471.      (M2LINK.EXE), other .EXE files, and the library and runtime support
  472.      object files (*.M2O and *.BIN).
  473.  
  474.      Assuming that you will use drive A for the compiler and utilities disk
  475.      and drive B as your work drive, add the following to your AUTOEXEC.BAT
  476.      file:
  477.  
  478.           SET PATH=A:
  479.           SET M2LIB=A:
  480.  
  481.      If you follow these suggestions, you may use all the system's
  482.      capabilities.  Just remember to swap the floppy in drive A before and
  483.      after invoking the linker from the compiler's menu. 
  484.  
  485.  
  486.  
  487.  
  488.      2.3 Recommended setup for a hard disk system
  489.  
  490.  
  491.      Place the executable files (*.EXE) and M2ED.CFG in a directory
  492.      currently in the DOS search path, or in a new directory (ex: \MODULA2)
  493.      to be added to the PATH list.  Example:
  494.  
  495.           SET PATH=C:\BIN;C:\MODULA2
  496.  
  497.      Make a directory for the library files (ex: \M2LIB) and copy all the
  498.      .DEF, .M2O and .BIN files to it.  To the AUTOEXEC.BAT file add the
  499.      line:
  500.  
  501.           SET M2LIB=C:\M2LIB
  502.  
  503.      You will probably want to create a directory for your own reusable
  504.      library modules.  This directory can be added to the M2LIB environment
  505.      variable.  Example:
  506.  
  507.           SET M2LIB=C:\M2LIB;C:\MYLIB
  508.  
  509.      You may keep your projects in their own, individual, directories. 
  510.  
  511.      
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.      A little tour through the system                                     9
  530.      
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.                                     Chapter 3
  539.  
  540.                         A little tour through the system
  541.  
  542.  
  543.  
  544.      After you finish the installation as described above, please copy the
  545.      files identified as the "system tour files" in the READ.ME file to
  546.      your work disk or directory. 
  547.  
  548.      Because we do not know your particular system configuration, in the
  549.      following examples we will assume the worst possible scenario. 
  550.      Therefore, some of the capabilities of this system will not be fully
  551.      exploited.  Specifically, we will not invoke the linker or run the
  552.      programs from the compiler menu, neither will we invoke a DOS shell to
  553.      run DBG2MAP.
  554.  
  555.      
  556.  
  557.  
  558.  
  559.  
  560.      3.1 The tour
  561.  
  562.  
  563.      First, we will look at the unnatural case of compiling, linking and
  564.      running a program that works the first time around.  Please execute
  565.      the following commands:
  566.  
  567.           MC SIEVE /C
  568.           M2LINK SIEVE /O
  569.  
  570.      Well, that's it!  Ready to run... 
  571.  
  572.           SIEVE
  573.  
  574.      Now for the more usual case:
  575.  
  576.           MC BADSIEVE
  577.  
  578.      From the compiler menu, select 'C' for compile. 
  579.  
  580.      Gee, that was quick!  Press RETURN to take a look at our errors... 
  581.  
  582.      The cursor is now positioned at the location of the first error. 
  583.      Using the keys Ctrl-E (find next error) and Ctrl-P (find previous
  584.      error) you may visit all the errors flagged by the compiler.  All the
  585.      while, the editor shows the error description on the top line of the
  586.      screen.  But, going back to the first error... 
  587.  
  588.      We really confused the compiler when we mistakenly typed in '.'
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.      A little tour through the system                                    10
  596.      
  597.  
  598.      instead of '..' in the range declaration.  Move the cursor back (left
  599.      arrow key) to where the '.' is, type in another '.', and that should
  600.      fix that!  As you will see as you type Ctrl-E, that single error
  601.      caused the compiler to dislike a few other things on that same line;
  602.      we will just ignore those errors and go on. 
  603.  
  604.      Go on to the next error location (line 22). This time, we should have
  605.      used a ']' but typed '}' instead.  The backspace key will delete the
  606.      offending character; now, type the ']' in its place. 
  607.  
  608.      And that is that.  Shall we try to compile the program again? 
  609.  
  610.      Press Alt-S to save the file, Alt-Q to leave the editor and, back at
  611.      the main menu, select 'C'.
  612.  
  613.      More errors?! 
  614.  
  615.           These errors should have been detected during pass2 of the
  616.           compiler; If not, you may try to fix these errors and recompile,
  617.           or you may opt for loading and compiling the new file
  618.           BADSIEV1.MOD, which contains the earlier fixes.
  619.  
  620.      Going back to the editor... 
  621.  
  622.      We find that we used the identifier 'cnt' which is undefined; we
  623.      really meant to use count.  So, moving the cursor around with the
  624.      cursor keys and/or deleting characters with the backspace or delete
  625.      key, please replace 'cnt' by 'count'.
  626.  
  627.      Searching for the next error... 
  628.  
  629.      The next error occured during the processing of the call to WriteCard.
  630.      What happened here is that WriteCard requires 2 parameters, the second
  631.      one being the size of the field to display.  So, to fix it, let's
  632.      insert a comma after 'count' and some number (for example 'count,4').
  633.  
  634.      Any more erors?  No, that is it... 
  635.  
  636.      We now save the file (Alt-S), quit the editor (Alt-Q) and recompile
  637.      (c).
  638.  
  639.      Now, the program should have compiled without errors.  If not, you may
  640.      recompile BADSIEV2.MOD instead. 
  641.  
  642.      We may now quit the compiler (q).
  643.  
  644.      By now, we have some program that has compiled clean (BADSIEVE,
  645.      BADSIEV1 or BADSIEV2). In what follows, we will assume all went well
  646.      and we have BADSIEVE.
  647.  
  648.      If you look at the directory, you will see the new object module
  649.      created as a result of the previous exercise (BADSIEVE.M2O). The
  650.      compiler always writes its output to a file with the extension 'M2O'.
  651.  
  652.      Let us link and test the program:
  653.  
  654.           M2LINK BADSIEVE /L
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.      A little tour through the system                                    11
  662.      
  663.  
  664.  
  665.      We use the /L option so that the line number information written out
  666.      by the compiler to the object file will be preserved by the linker. 
  667.      We will need this information later. 
  668.  
  669.           BADSIEVE
  670.  
  671.      A runtime error?  And it gives us a PC location.  Very informative, is
  672.      it not?  How in the world are we supposed to fix the program based on
  673.      that?  Do not dispair! 
  674.  
  675.      Looking at your directory, you will notice that the linker created 2
  676.      files: BADSIEVE.EXE and BADSIEVE.DBG.
  677.  
  678.      No, TYPEing BADSIEVE.DBG does not help, it just displays garbage.  But
  679.      we have a utility called DBG2MAP that will convert the information in
  680.      that file to a DOS LINK compatible MAP file.  Let's try it:
  681.  
  682.           DBG2MAP BADSIEVE
  683.  
  684.      Now, using your favorite editor (or the editor in MC: MC BADSIEVE.MAP
  685.      and then E), look at the contents of BADSIEVE.MAP. In the last few
  686.      lines of the file, we have the line number information for BADSIEVE.
  687.      If you look up the line whose address is closest (but lower) to the PC
  688.      in the error message, you get the number of the line where the error
  689.      occured (line 22).
  690.  
  691.      Let's see what happened... 
  692.  
  693.           MC BADSIEVE
  694.  
  695.      Pick 'E' to go into the editor and, either move the cursor down to the
  696.      line indicated by your research, or let the editor find it with Alt-G.
  697.  
  698.      So, what is the problem?  Well, we declared the 'flag' array to have a
  699.      maximum index of 8190, but 'j' got bigger than that (the FOR loop will
  700.      increment 'j' up to the value of 10000).
  701.  
  702.      You may fix the problem by deleting the '10000' and typing in its
  703.      place 'SIZE'.
  704.  
  705.      Recompile the program, link it, and run it.  Did it work?  Good.
  706.  
  707.      It is time for you to experiment on your own.  But, before you do much
  708.      more, you may want to check out the Editor chapter of the
  709.      documentation. 
  710.  
  711.      
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.      The Compiler                                                        12
  728.      
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.                                     Chapter 4
  737.  
  738.                                   The Compiler
  739.  
  740.  
  741.  
  742.      In Modula-2, identifiers may be used before they are declared, except
  743.      when they are used in another declaration (this restriction does not
  744.      apply to pointers).  This forces the compilation process to be done in
  745.      at least two passes.  To avoid imposing unnecessary restrictions and,
  746.      yet, provide reasonable performance, the two pass approach was
  747.      selected: During the first pass, syntax analysis and declaration
  748.      analysis are performed; The second pass performs the semantic analysis
  749.      and code generation. 
  750.  
  751.      The compiler has an integrated text editor.  Should errors be
  752.      encountered, the editor is invoked at the end of the current compiler
  753.      pass (sooner, if an error is found during the processing of an import
  754.      list or if 20 errors are identified). 
  755.  
  756.      The compiler also has a built in "make" processor.  A makefile must be
  757.      created before this process is invoked.  Although you can create a
  758.      makefile using the editor, we recommend that you use the utility
  759.      provided for that purpose: GENMAKE (this utility may be invoked from
  760.      the compiler menu -- G).
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.      The Compiler                                                        13
  794.      
  795.  
  796.  
  797.  
  798.  
  799.  
  800.      4.1 Running the integrated compiler: MC
  801.  
  802.  
  803.      Compiler invocation:
  804.  
  805.           MC [workModule] [/p mainModule] [/c] [/e] [/m]
  806.  
  807.      The '/p' option may be used to indicate the name of the main module of
  808.      the program that you are working on (the name should not have an
  809.      extension).  If this option is not used, but workModule is entered
  810.      without an extension, then the same name is also used for mainModule. 
  811.  
  812.      If you use of the '/c' command line option, the compiler starts
  813.      compiling "workModule" immediately and, if no errors are encountered,
  814.      will bring you right back to the DOS prompt.  This is useful when
  815.      running the compiler from a batch file:
  816.  
  817.           MC myprog /c
  818.  
  819.      The '/e' option will send you straight into the editor. 
  820.  
  821.      The '/m' option invokes the make processor, which will look for the
  822.      file mainModule.MAK for the dependencies list. 
  823.  
  824.      The compiler always sets the DOS errorlevel to 0 if the last compile
  825.      was successful (no errors); otherwise, the DOS errorlevel is set to 1.
  826.  
  827.      If the compiler is invoked without the '/c', '/e' or '/m' options, you
  828.      will get a screen that looks something like this:
  829.  
  830.  
  831.           Modula-2 compiler, Version 1.1
  832.           (C) Copyright 1987 Fitted Software Tools.
  833.           All rights reserved.
  834.  
  835.           Memory model in use: LARGE
  836.  
  837.           Heap in use:                   0K
  838.           Available Heap:              229K
  839.  
  840.           Program:     sieve
  841.  
  842.           Work module: sieve.MOD
  843.  
  844.           Program  New   Options  DOS   Quit
  845.           Compile  Edit  Genmake  Make  Link  eXecute >
  846.  
  847.  
  848.      The options at this point are:
  849.  
  850.      Program           Specify the name of the main program module. 
  851.  
  852.      New               Specify another "Work module". 
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.      The Compiler                                                        14
  860.      
  861.  
  862.  
  863.      Options           To select the memory model to use. 
  864.  
  865.      DOS               Invoke a new DOS shell.  At the DOS prompt, you
  866.                        should type EXIT to return to this system. 
  867.  
  868.      Quit              Return to DOS.
  869.  
  870.      Compile           Compile the "Work module". 
  871.  
  872.      Edit              Edit the "Work module". 
  873.  
  874.      Genmake           Invoke the GenMake program, passing as argument the
  875.                        name in Program.
  876.  
  877.      Make              Recompile all the necessary modules as per the rules
  878.                        of a makefile (The makefile is assumed to have the
  879.                        name in Program and the extension of .MAK). Note: If
  880.                        errors are encountered during the compilation of one
  881.                        of the modules, the make process is aborted.  After
  882.                        fixing the errors, select Make again. 
  883.  
  884.      Link              Invokes the linker (M2Link) passing along as
  885.                        arguments the name in Program and '/L'.
  886.  
  887.      eXecute           Program is executed. 
  888.  
  889.      
  890.  
  891.  
  892.  
  893.  
  894.      4.2 Running the freestanding compiler: M2COMP
  895.  
  896.  
  897.      Compiler invocation:
  898.  
  899.           M2COMP filename [/m]
  900.  
  901.      filename is the name of the module to compile or, if the /M option is
  902.      used, the name of the makefile to process. 
  903.  
  904.      The DOS errorexit is set to 0 if the compilation (make) is successful
  905.      and to 1 otherwise. 
  906.  
  907.      
  908.  
  909.  
  910.  
  911.  
  912.      4.3 The compilation process
  913.  
  914.  
  915.      
  916.  
  917.  
  918.      4.3.0.1 The input file
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.      The Compiler                                                        15
  926.      
  927.  
  928.  
  929.      If the module to be compiled is already loaded into one of the editor
  930.      buffers, that source is compiled.  Otherwise, the compiler tries to
  931.      open the named file. 
  932.  
  933.      
  934.  
  935.  
  936.      4.3.0.2 The imported modules
  937.  
  938.      The compiler and the linker cooperate in assuring that all the modules
  939.      that refer to a particular definition module will have been compiled
  940.      against the same version of that definition module. 
  941.  
  942.      To this end, the compiler places in the 'module header' and 'module
  943.      import' records of the object file a "module key".  This module key is
  944.      the date of the DEF file used during the compilation of the
  945.      implementation module or during the processing of the IMPORT
  946.      statement. 
  947.  
  948.      Due to this, the compiler will not look in the editor buffers for the
  949.      DEF files needed to process an IMPORT list.  These are always read in
  950.      from the disk. 
  951.  
  952.      
  953.  
  954.  
  955.      4.3.0.3 The output file
  956.  
  957.      The output from the compilation of a main module or an implementation
  958.      module is a single output file, with the same name of the source file
  959.      but with the extension of 'M2O' (Modula-2 Object).
  960.  
  961.      The compilation of a definition module does not generate any new
  962.      output files.  If the compilation is successful (no errors), the
  963.      compiler simply 'touches' the source file, updating its modification
  964.      time. 
  965.  
  966.      
  967.  
  968.  
  969.      4.3.0.4 A warning
  970.  
  971.      Because of the fact that the compiler uses the date of the DEF file as
  972.      that module's key, you may not modify a DEF file unless you intend to
  973.      recompile all the modules that use it, nor can you copy the file in
  974.      such a way that its date is not preserved. 
  975.  
  976.      In particular, if you are going to be transferring your modules
  977.      between computers, you must use some procedure that will preserve all
  978.      the DEF files' dates. 
  979.  
  980.      
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.      The Compiler                                                        16
  992.      
  993.  
  994.      4.4 Compiler directives
  995.  
  996.  
  997.      Certain compiler code generation options may be set through directives
  998.      included in the program text.  These directives must appear
  999.      immediately at the beginning of a comment; multiple directives may be
  1000.      entered in a single comment by separating them by commas.  Example
  1001.  
  1002.           (* $S-, $R+ *)
  1003.  
  1004.      A '+' sets the directive to TRUE, a '-' sets it to FALSE.
  1005.  
  1006.      The following compiler directives are defined:
  1007.  
  1008.      $A                Alignment. Default $A+. If enabled, all new variables
  1009.                        declared are aligned on a word boundary.  Record
  1010.                        fields are packed (not aligned) regardless of the
  1011.                        setting of this option. 
  1012.  
  1013.      $S                Stack overflow checking.  Default $S+. If enabled,
  1014.                        stack overflow checking is performed on entry to a
  1015.                        procedure and when copying open arrays to a
  1016.                        procedure's local stack frame. 
  1017.  
  1018.      $R                Range checking.  Default $R+. If enabled, before any
  1019.                        assignment is made to a variable of a subrange type,
  1020.                        the value to be assigned is tested against the limits
  1021.                        of the subrange type. 
  1022.  
  1023.      $T                Array subscript checking.  Default $T+. If enabled,
  1024.                        any time a subscript operation is performed on an
  1025.                        array, the subscript value is checked to confirm that
  1026.                        the operation would not generate an address outside
  1027.                        the bounds of the array. 
  1028.  
  1029.      $L                Generate line number information.  Default $L-. If
  1030.                        this option is enabled, the compiler will include a
  1031.                        list of source code line numbers and their
  1032.                        corresponding object code offsets in the output
  1033.                        file.  This line number information is passed on to
  1034.                        the .DBG file when the program is linked with the /L
  1035.                        option. 
  1036.  
  1037.      
  1038.  
  1039.  
  1040.  
  1041.  
  1042.      4.5 Runtime errors
  1043.  
  1044.  
  1045.      When, during the execution of a program, a runtime error is detected,
  1046.      the runtime error handler will terminate the program and write out a
  1047.      message indicating the type of error encountered and its location (PC
  1048.      address). 
  1049.  
  1050.      To find the location of the error in the source code, run DBG2MAP
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.      The Compiler                                                        17
  1058.      
  1059.  
  1060.      against the .DBG file generated by M2LINK for this program.  Scanning
  1061.      the .MAP file created, you should be able to always determine the
  1062.      module and procedure where the error occured.  If the $L+ directive
  1063.      was used when compiling the module in question and the /L option was
  1064.      used when linking the program, the error location can be pinpointed to
  1065.      the offending line by scanning the line number information at the end
  1066.      of the .MAP file. 
  1067.  
  1068.      
  1069.  
  1070.  
  1071.      4.5.1 Trapping runtime errors in your program
  1072.  
  1073.      The Library module System provides you with a means of intercepting
  1074.      runtime errors.  The following are the currently defined runtime error
  1075.      numbers that may be passed to your error handler routine:
  1076.  
  1077.           0   stack overflow ($S option)
  1078.           1   range error ($R or $T option)
  1079.           2   integer/cardinal overflow (divide by zero)
  1080.           3   floating point error
  1081.           4   function did not execute a RETURN
  1082.           5   HALT was invoked
  1083.  
  1084.  
  1085.  
  1086.  
  1087.      4.6 Compiler size limits
  1088.  
  1089.  
  1090.      The following are the code and data size limits imposed by this
  1091.      compiler:
  1092.  
  1093.        -  A string constant cannot exceed 80 characters.  This is also the
  1094.           limit set for the size of any identifier. 
  1095.  
  1096.        -  When using the HUGE memory model, each compilation module is
  1097.           assigned its own data segment, which can be up to 64k in size. 
  1098.           In the data segment, the compiler allocates the space for all the
  1099.           module's global variables and some of the module's constants. 
  1100.  
  1101.        -  When using the LARGE memory model, all the modules' data are
  1102.           combined, at link time, into a single data segment (64k
  1103.           maximum). 
  1104.  
  1105.        -  The maximum size of a data structure is 65532 bytes. 
  1106.  
  1107.        -  The maximum amount of space allocated for variables local to a
  1108.           procedure is 32000 bytes. 
  1109.  
  1110.        -  The compiler will also refuse to generate the code to pass, in a
  1111.           procedure call, by value, a parameter greater than 65000 bytes in
  1112.           size. 
  1113.  
  1114.      The following are the compiler's internal limits:
  1115.  
  1116.        -  The maximum number of different (namewise) identifiers that can
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.      The Compiler                                                        18
  1124.      
  1125.  
  1126.           be processed in a single compilation is 2000.
  1127.  
  1128.        -  The total number of characters in all the different (namewise)
  1129.           identifiers processed cannot exceed 12000 characters. 
  1130.  
  1131.        -  No single procedure can be translated into more than 10k of
  1132.           object code. 
  1133.  
  1134.        -  An array of 8k bytes is used to keep track of all the initialized
  1135.           data for a module.  This imposes a limit on the total amount of
  1136.           string, real and long constants used in the compilation module. 
  1137.  
  1138.  
  1139.  
  1140.  
  1141.      4.7 The language supported
  1142.  
  1143.  
  1144.      This release of the compiler will translate a program written in the
  1145.      Modula-2 language as defined by Niklaus Wirth in the 3rd edition of
  1146.      his book "Programming in Modula-2", with the exceptions noted bellow:
  1147.  
  1148.      
  1149.  
  1150.        -  Integer and Cardinal arithmetic overflow is not detected. 
  1151.  
  1152.        -  ASM is a reserved word in this implementation. 
  1153.  
  1154.        -  For those programmers that "grew up" in the Hex world, a way to
  1155.           define CHAR literals in Hex is provided: 20X corresponds to the
  1156.           "space" character in ASCII.
  1157.  
  1158.      
  1159.  
  1160.  
  1161.      4.7.1 LONGINT and LONGCARD
  1162.  
  1163.      This compiler implements the standard types LONGINT and LONGCARD.
  1164.  
  1165.      Operands of the type LONGINT or LONGCARD may appear in any expression,
  1166.      just like INTEGER or CARDINAL. But that is about it! 
  1167.  
  1168.      Subranges of these types are not supported. 
  1169.  
  1170.      No standard procedure, except INC, DEC and the ones listed later in
  1171.      this document will accept operands of one of these types. 
  1172.  
  1173.      A variable of type LONGINT or LONGCARD cannot be used as the control
  1174.      variable in a FOR loop.  Neither can CASE labels be of a LONG type. 
  1175.  
  1176.      Constants of type LONGINT or LONGCARD can be coded in decimal only and
  1177.      are terminated by an 'L'. Example
  1178.  
  1179.           123L is a valid LONGCARD or LONGINT constant
  1180.  
  1181.           -348762L is a valid LONGINT constant
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.      The Compiler                                                        19
  1190.      
  1191.  
  1192.           565656 -89076 are CARDINAL and INTEGER constants out of range
  1193.  
  1194.  
  1195.      4.7.2 Additional standard procedures
  1196.  
  1197.  
  1198.      4.7.2.1 NEW and DISPOSE
  1199.  
  1200.      NEW and DISPOSE have been deleted from the language definition in the
  1201.      3rd edition of Wirth's book.  We implement them thus:
  1202.  
  1203.           NEW(p)
  1204.  
  1205.      Invokes the procedure ALLOCATE, which must conform to the type:
  1206.  
  1207.           PROCEDURE ( VAR ADDRESS, CARDINAL )
  1208.  
  1209.      passing along p and the size of the object p is defined as pointing
  1210.      to. 
  1211.  
  1212.           DISPOSE(p)
  1213.  
  1214.      Invokes the procedure DEALLOCATE, which must conform to the type:
  1215.  
  1216.           PROCEDURE ( VAR ADDRESS, CARDINAL )
  1217.  
  1218.      passing along p and the size of the object p is defined as pointing
  1219.      to. 
  1220.  
  1221.      The procedures ALLOCATE and DISPOSE must, therefore, be defined in the
  1222.      module using NEW and/or DISPOSE, or imported from some other module,
  1223.      like Storage.
  1224.  
  1225.      
  1226.  
  1227.  
  1228.      4.7.2.2 LONG and SHORT
  1229.  
  1230.           PROCEDURE LONG( INTEGER ) :LONGINT;
  1231.  
  1232.           PROCEDURE LONG( CARDINAL ) :LONGCARD;
  1233.  
  1234.           PROCEDURE SHORT( LONGINT ) :INTEGER;
  1235.  
  1236.           PROCEDURE SHORT( LONGCARD ) :CARDINAL;
  1237.  
  1238.      LONG takes an INTEGER (CARDINAL) and converts it into a LONGINT
  1239.      (LONGCARD).
  1240.  
  1241.      SHORT takes a LONGINT (LONGCARD) and converts it into an INTEGER
  1242.      (CARDINAL).
  1243.  
  1244.  
  1245.  
  1246.  
  1247.      4.8 Objects exported by the pseudo module SYSTEM
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.      The Compiler                                                        20
  1256.      
  1257.  
  1258.  
  1259.  
  1260.      4.8.0.1 TYPE BYTE
  1261.  
  1262.      Takes 1 byte of storage.  Only assignment is defined for this type. 
  1263.      If the formal parameter of a procedure is of type BYTE, the
  1264.      corresponding actual parameter may be of any type that takes 1 byte of
  1265.      storage. 
  1266.  
  1267.      If the formal parameter of a procedure is of type ARRAY OF BYTE, the
  1268.      corresponding actual parameter may be of any type. 
  1269.  
  1270.  
  1271.      4.8.0.2 TYPE WORD
  1272.  
  1273.      Takes 1 word (2 bytes) of storage.  Only assignment is defined for
  1274.      this type.  If the formal parameter of a procedure is of type WORD,
  1275.      the corresponding actual parameter may be of any type that takes 1
  1276.      word of storage. 
  1277.  
  1278.      If the formal parameter of a procedure is of type ARRAY OF WORD, the
  1279.      corresponding actual parameter may be of any type.  Care should be
  1280.      taken in this case, as the size of the parameter passed is rounded up
  1281.      to an even size. 
  1282.  
  1283.  
  1284.      4.8.0.3 TYPE ADDRESS
  1285.  
  1286.      The type ADDRESS is compatible with all pointer types.  ADDRESS itself
  1287.      is defined as a POINTER TO WORD. In this implementation, the type
  1288.      ADDRESS is not compatible with any arithmetic type.  This is due to
  1289.      the fact that the Intel 8086 series processors use segmented
  1290.      addresses.  It would not be hard to implement automatic conversions
  1291.      between LONGCARD and ADDRESS but it is felt that this would be
  1292.      contrary to the spirit of the language, whereby the compiler is not
  1293.      expected to perform any "magic" tricks.  Instead, two functions are
  1294.      provided for that purpose: FLAT and PTR.
  1295.  
  1296.      In release 1.2 we relaxed the above a little.  ADDRESS + CARDINAL and
  1297.      ADDRESS - CARDINAL are legal expressions.  The CARDINAL is added or
  1298.      subtracted from the offset portion of the ADDRESS and the result is
  1299.      still an ADDRESS.
  1300.  
  1301.      Also new in release 1.2 is the capability of INC and DEC to take an
  1302.      ADDRESS as their first argument.  The operation is, however, performed
  1303.      on the offset portion of the ADDRESS only. 
  1304.  
  1305.      
  1306.  
  1307.  
  1308.      4.8.0.4 SEG and OFS
  1309.  
  1310.      These are field definitions for POINTER types.  If you import these,
  1311.      you may access the segment or offset portions of a pointer variable
  1312.      using regular field selection syntax.  Example
  1313.  
  1314.           pointer.SEG :segment portion of pointer
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.      The Compiler                                                        21
  1322.      
  1323.  
  1324.  
  1325.  
  1326.      4.8.0.5 PROCEDURE ADR
  1327.  
  1328.      ADR( designator ) Returns the address of designator (type ADDRESS).
  1329.  
  1330.  
  1331.      4.8.0.6 PROCEDURE FLAT
  1332.  
  1333.      FLAT( ADDRESS ) returns a LONGCARD "flat" address. 
  1334.  
  1335.  
  1336.      4.8.0.7 PROCEDURE PTR
  1337.  
  1338.      PTR( LONGCARD ) returns an ADDRESS corresponding to the "flat" address
  1339.      represented by the LONGCARD.
  1340.  
  1341.  
  1342.      4.8.0.8 PROCEDURE SEGMENT
  1343.  
  1344.      SEGMENT( designator ) returns the segment portion of the address of
  1345.      'designator'. Example:
  1346.  
  1347.           DX := SEGMENT( buffer ); would assign to DX the segment value of
  1348.           ADR(buffer).
  1349.  
  1350.  
  1351.      4.8.0.9 PROCEDURE OFFSET
  1352.  
  1353.      OFFSET( designator ) returns the offset portion of the address of
  1354.      'designator'.
  1355.  
  1356.  
  1357.      4.8.0.10 PROCEDURE NEWPROCESS
  1358.  
  1359.      NEWPROCESS(p:PROC; a:ADDRESS; n:CARDINAL; VAR p1:ADDRESS)
  1360.  
  1361.      creates a new process whose entry point is p and workspace is at a for
  1362.      n bytes.  p1 is the new process pointer.  This process is not
  1363.      activated until a TRANSFER to p1 is done. 
  1364.  
  1365.      The starting priority of the new process is the current processor
  1366.      priority at the time NEWPROCESS is invoked (please refer to the
  1367.      section on Module Priorities).
  1368.  
  1369.  
  1370.      4.8.0.11 PROCEDURE TRANSFER
  1371.  
  1372.      TRANSFER( VAR p1, p2 :ADDRESS)
  1373.  
  1374.      suspends the current process, assigning it to p1 and resumes p2.  The
  1375.      current process' value is assigned to p1 only after p2 has been
  1376.      identified; it is, therefore, okay for p1 and p2 to be the same. 
  1377.  
  1378.      The process is resumed at the same priority level that it was running
  1379.      at, at the time of suspension. 
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.      The Compiler                                                        22
  1388.      
  1389.  
  1390.  
  1391.  
  1392.      4.8.0.12 PROCEDURE IOTRANSFER
  1393.  
  1394.      IOTRANSFER( VAR p1, p2 :ADDRESS; intVector :CARDINAL )
  1395.  
  1396.      issues a TRANSFER from p1 to p2 (just the way TRANSFER does it) after
  1397.      installing the current process for reactivation when an interrupt
  1398.      comes in through interrupt vector intVector. 
  1399.  
  1400.      When the interrupt occurs, the interrupt vector is reloaded with its
  1401.      previous value.  A TRANSFER is done to the I/O process (the one that
  1402.      issued the IOTRANSFER) such that p2 now contains the value of the
  1403.      process that was running when the interrupt occured. 
  1404.  
  1405.  
  1406.      4.8.0.13 ASSEMBLER
  1407.  
  1408.      An 8086 inline assembler is provided.  Once ASSEMBLER is imported from
  1409.      SYSTEM, you can enter inline assembler code by bracketing it with the
  1410.      keywords ASM and END.
  1411.  
  1412.      Assembler input is free form.  Comments are entered as in regular
  1413.      Modula-2. Example
  1414.  
  1415.           loop:   CMP  BYTE [SI], 0   (*end of string?*)
  1416.                   MOV  BYTE [DI], [SI]
  1417.                   INC  SI  INC DI     (*increment pointers*)
  1418.                   JMP  loop
  1419.  
  1420.      The assembler accepts all the 8086/8088 opcode mnemonics.  Address
  1421.      operands can be coded in just about any form acceptable to other
  1422.      assemblers, except that the only operator supported if '+'. Operand
  1423.      type overrides are: WORD, BYTE, FAR, NEAR and are not to be followed
  1424.      by the keyword POINTER or PTR. Example
  1425.  
  1426.           label:  MOV  AX, ES:[BX,DI+5]
  1427.                   MOV  AX, ES:5[DI+BX]
  1428.                   MOV  WORD [5], 1
  1429.                   CALL NEAR [DI]
  1430.                   TEST BYTE i+2, 1
  1431.  
  1432.      All the mnemonics and register names must be entered in upper case. 
  1433.      In case you need to use a Modula-2 name that conflicts with one of the
  1434.      assembler reserved symbols, you may precede it with a '@'. Example
  1435.  
  1436.           MOV @AX, AX
  1437.  
  1438.      would generate a move from register AX to variable AX.
  1439.  
  1440.      All modula-2 variables can generaly be accessed in assembler.  Record
  1441.      field names are not accessible from assembler.  The assembler will not
  1442.      automatically do anything for you.  For example: if you specify a VAR
  1443.      parameter as an operand to an instruction, you are naming the address
  1444.      of the pointer to the actual parameter.  Example
  1445.  
  1446.           PROCEDURE p( VAR done :BOOLEAN );
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.      The Compiler                                                        23
  1454.      
  1455.  
  1456.           ...
  1457.           ASM
  1458.                LES  DI, done
  1459.                MOV  BYTE ES:[DI], TRUE
  1460.           END;
  1461.  
  1462.      is the correct way of storing TRUE in done. 
  1463.  
  1464.      The following types of constants may be accessed in assembler:
  1465.      INTEGER, CARDINAL, BOOLEAN, CHAR and enumeration constants. 
  1466.  
  1467.      All labels declared inside an ASM section are local to that section of
  1468.      code.  But labels names cannot match some name known in the scope of
  1469.      the current procedure.  Labels can only be referenced in jump
  1470.      instructions. 
  1471.  
  1472.      All jumps are optimized by the compiler.  There is, therefore, no need
  1473.      (or capability) to specify the size of a jump.  In particular, the
  1474.      compiler will turn a conditional jump out of range into a reverse
  1475.      conditional jump over a far jump to the original destination. 
  1476.  
  1477.      Remember, this is a Modula-2 compiler, not an assembler!  The inline
  1478.      assembler capability is provided for use in exceptional situations
  1479.      only. 
  1480.  
  1481.      
  1482.  
  1483.  
  1484.  
  1485.  
  1486.      4.9 The generated object code
  1487.  
  1488.  
  1489.      
  1490.  
  1491.  
  1492.      4.9.1 Data type representation
  1493.  
  1494.      CHAR              1 byte
  1495.  
  1496.      INTEGER           2 bytes 2's complement
  1497.  
  1498.      CARDINAL          2 bytes
  1499.  
  1500.      LONGCARD          4 bytes
  1501.  
  1502.      LONGINT           4 bytes 2's complement
  1503.  
  1504.      BOOLEAN           1 byte (1=TRUE, 0=FALSE)
  1505.  
  1506.      REAL              4 bytes Intel 8087 format. 
  1507.  
  1508.      BITSET            1 word.  0 is low order bit, 15 is high order bit. 
  1509.  
  1510.      Enumerations      1 byte
  1511.  
  1512.      SETs              1 to 8 words (sets of up to 256 elements)
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.      The Compiler                                                        24
  1520.      
  1521.  
  1522.  
  1523.      POINTERs          4 bytes in Intel 8086/88 format
  1524.  
  1525.      PROCEDUREs        4 bytes POINTER to procedure entry point
  1526.  
  1527.      Addresses are represented in the default Intel 8086 format:
  1528.  
  1529.           1 word          byte offset
  1530.  
  1531.           1 word          segment
  1532.  
  1533.      Numeric values are likewise represented the way the Intel 8086
  1534.      processor family likes them: low order byte first, high order byte
  1535.      last. 
  1536.  
  1537.      
  1538.  
  1539.  
  1540.      4.9.2 The runtime memory map
  1541.  
  1542.      Currently, the compiler generates code using the "large" or "huge"
  1543.      memory model only. 
  1544.  
  1545.      In the "huge" memory model, each module has its own data and code
  1546.      segments. 
  1547.  
  1548.      In the "large" memory model, each module has its own code segment. 
  1549.      The entire program has one data segment. 
  1550.  
  1551.      The linker binds all the code segments first, and then all the data
  1552.      segments.  The stack is allocated above the data segments.  All the
  1553.      remainning memory is available for the heap. 
  1554.  
  1555.      When a program is loaded for execution, here is what the memory looks
  1556.      like:
  1557.  
  1558.  
  1559.           From low to high addresses:
  1560.  
  1561.           0         ----------------------------------------------
  1562.                     I  Interrupt vectors                         I
  1563.                     I  DOS                                       I
  1564.           PSP       I  Program segment prefix                    I
  1565.           PSP+100h  I  Program Code segments                     I
  1566.                     I  Program Data segment(s)                   I
  1567.           StackSeg  I  Stack                                     I
  1568.           HeapTop   I  Heap                                      I
  1569.                     I  ...                                       I
  1570.                     I  DOS Command (resident portion)            I
  1571.           MemTop    ----------------------------------------------
  1572.  
  1573.      Label names on the left are the ones exported by System.
  1574.  
  1575.      This system uses interrupt vector 192 (0C0H) at location 0000:0300.
  1576.      Interrupt 192 is issued by a program when a runtime error occurs, when
  1577.      HALT is invoked or when a coroutine other than the main one terminates
  1578.      via a return. 
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.      The Compiler                                                        25
  1586.      
  1587.  
  1588.  
  1589.      The first word (offset 0) in every code segment contains the data
  1590.      segment value for that particular module (for the program, in the case
  1591.      of the "large" memory model. 
  1592.  
  1593.  
  1594.      4.9.3 Procedure calling conventions
  1595.  
  1596.      Procedure parameters are pushed into the stack 1st argument first. 
  1597.      Control is then transferred to the procedure through a FAR call.  It
  1598.      is the called procedure's responsibility to remove its parameters from
  1599.      the stack before returning. 
  1600.  
  1601.      
  1602.  
  1603.  
  1604.      4.9.3.1 Parameter passing (all except open array parameters)
  1605.  
  1606.      If the formal parameter of a procedure is a value parameter, the
  1607.      actual parameter is copied into the stack. 
  1608.  
  1609.      If the formal parameter is a variable parameter (VAR), the address of
  1610.      the actual parameter is pushed into the stack (first the segment
  1611.      portion of the address and then the offset part). 
  1612.  
  1613.      
  1614.  
  1615.  
  1616.      4.9.3.2 Parameter passing (open array parameters)
  1617.  
  1618.      If the formal parameter is an open array, the address and HIGH value
  1619.      of the corresponding formal parameter are pushed into the stack (HIGH
  1620.      value first, and then the address, as above). 
  1621.  
  1622.      If the open array parameter is a value parameter, the value of the
  1623.      actual parameter is copied into the stack on procedure entry. 
  1624.  
  1625.      
  1626.  
  1627.  
  1628.      4.9.3.3 Returning values from a function procedure
  1629.  
  1630.      One byte results are returned in AL, two byte results are returned in
  1631.      AX, and four byte results are returned in DX:AX (DX has the high order
  1632.      part of the result). 
  1633.  
  1634.      
  1635.  
  1636.  
  1637.  
  1638.  
  1639.      4.10 Module priorities
  1640.  
  1641.  
  1642.      Eight module priority levels are supported in this implementation,
  1643.      from 0 (highest priority) to 7.
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.      The Compiler                                                        26
  1652.      
  1653.  
  1654.      Priorities are implemented by masking off, on the 8259 interrupt
  1655.      controller, all the interrupts at or below the current priority
  1656.      level. 
  1657.  
  1658.      Because the PC usually runs with several of the interrupt levels
  1659.      disabled, it is not easy to decide what the interrupt mask for the
  1660.      value for "no priority" should be for your particular application. 
  1661.      The implementation of NEWPROCESS, therefore, assumes that you have
  1662.      enabled all the interrupts that your program will be capable of
  1663.      processing before you create your processes.  The value in the
  1664.      interrupt mask register of the 8259 at the time of process creation
  1665.      will determine the initial priority level of this process, once it
  1666.      gets started.  Because of this, invoking NEWPROCESS from inside a
  1667.      priority module is usually not what you want to do! 
  1668.  
  1669.      Execution priorities are changed when entering/exitting procedures in
  1670.      modules that have a priority specification, and during the execution
  1671.      of some form of a TRANSFER.
  1672.  
  1673.      We highly recommend that you study the communications program
  1674.      provided, paying particular attention to the module Kernel, for an
  1675.      example of how to use priorities with this system. 
  1676.  
  1677.      NOTE: The compiler does not restrict the priority level specified (any
  1678.      number will do).  You must, therefore, exercise care in defining a
  1679.      module's priority level.  On the other hand, it is easy to add
  1680.      additional priority levels by simply modifying the runtime module
  1681.      M2Procs.
  1682.  
  1683.      
  1684.  
  1685.  
  1686.  
  1687.  
  1688.      4.11 Memory models
  1689.  
  1690.  
  1691.      In general, you may compile the same code under either the LARGE or
  1692.      the HUGE memory model. 
  1693.  
  1694.      The only factor to consider is when using inline assembler. 
  1695.  
  1696.      Under the HUGE memory model, the compiler generates code to reload DS
  1697.      after any invocation of an imported procedure or a VARiable
  1698.      procedure.  Under the LARGE memory model, this is not necessary as a
  1699.      single data segment is defined.  If you write some inline assembler
  1700.      code that modifies DS, please restore it, even if the next thing you
  1701.      do is a RETurn; this way, your routine will work regardless of whether
  1702.      you use the LARGE or the HUGE memory model. 
  1703.  
  1704.      Under the HUGE memory model, access to external variables is done
  1705.      through an indirect pointer, whereas in the LARGE memory model the
  1706.      external variable resides in the programs ONLY data segment and is,
  1707.      therefore directly accessible. 
  1708.  
  1709.      
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.      The Text Editor                                                     27
  1718.      
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.                                     Chapter 5
  1727.  
  1728.                                  The Text Editor
  1729.  
  1730.  
  1731.  
  1732.      The text editor included in this package has all the features that you
  1733.      have come to expect from a basic program editor: the ability to
  1734.      insert, delete, move, find and replace text; support for concurrent
  1735.      editing of multiple files (as many as will fit in memory) in separate
  1736.      windows (as many as will fit on the screen) with the ability to copy
  1737.      or move text from window to window. 
  1738.  
  1739.      Although you may load the same file in two different windows, the
  1740.      editor will not be aware of the fact and will treat the two copies as
  1741.      two different files. 
  1742.  
  1743.      The only preset limitation in the editor is that it cannot handle
  1744.      files bigger than 64k. This decision was justified by the fact that
  1745.      Modula-2 programs are supposed to be modular.  File load/save speed
  1746.      was the overriding factor here. 
  1747.  
  1748.      All the text editor keys are defined by the user through the use of
  1749.      the EDCONFIG program.  When the editor starts, it expects to find the
  1750.      file M2ED.CFG in the current PATH.
  1751.  
  1752.      M2ED.CFG will also tell the editor what display colors (attributes) to
  1753.      use for the Status line, for Normal text and for Marked text blocks. 
  1754.  
  1755.      Finally, M2ED.CFG also contains the default settings for the TAB size
  1756.      value, as well as whether or not the editor will expand the tabs
  1757.      inserted into the text spaces.  Note: Tabs present in a file will not
  1758.      be expanded to spaces by the editor. 
  1759.  
  1760.      To get you started, we provide a M2ED.CFG file with the following
  1761.      definitions:
  1762.  
  1763.           Cursor left                    : Left
  1764.           Cursor right                   : Right
  1765.           Cursor up                      : Up
  1766.           Cursor down                    : Down
  1767.           Previous word                  : ^Left
  1768.           Next word                      : ^Righ
  1769.           Page up                        : PgUp
  1770.           Page down                      : PgDn
  1771.           Cursor to beginning of line    : Home
  1772.           Cursor to end of line          : End
  1773.           Cursor to top of window        : ^Home
  1774.           Cursor to bottom of window     : ^End
  1775.           To beginning of file           : ^PgUp
  1776.           To end of file                 : ^PgDn
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.      The Text Editor                                                     28
  1784.      
  1785.  
  1786.           Current line to top of window  : AltT
  1787.           Toggle insert/overtype         : Ins
  1788.           Delete character under cursor  : Del
  1789.           Delete previous character      : ^H
  1790.           Delete Current Line            : ^Y
  1791.           Delete to EOL                  : AltY
  1792.           Delete Word                    : ^D
  1793.           New file                       : AltN
  1794.           Read file                      : AltR
  1795.           Write block                    : AltW
  1796.           Save file                      : AltS
  1797.           Open window                    : ^O
  1798.           Close Window                   : ^C
  1799.           Next window                    : F2
  1800.           Previous window                : aF2
  1801.           Split screen                   : ^S
  1802.           Mark beginning of block        : F7
  1803.           Mark end of block              : F8
  1804.           Goto beginning of block        : AltB
  1805.           Goto end of block              : AltE
  1806.           Clear block marks              : AltH
  1807.           Copy block                     : AltC
  1808.           Delete block                   : AltD
  1809.           Move block                     : AltM
  1810.           Search forward                 : F5
  1811.           Search backwards               : aF5
  1812.           Replace forward                : F6
  1813.           Replace backwards              : aF6
  1814.           Global replace                 : ^F6
  1815.           Repeat last search/replace     : F1
  1816.           Goto next error                : ^E
  1817.           Goto previous error            : ^P
  1818.           Goto line                      : AltG
  1819.           Set options                    : AltO
  1820.           Redraw the screen              : ^L
  1821.           Quit                           : AltQ
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.      The Linker                                                          29
  1850.      
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.                                     Chapter 6
  1859.  
  1860.                                    The Linker
  1861.  
  1862.  
  1863.  
  1864.      The linker is invoked by the command line
  1865.  
  1866.           M2LINK myprog [/s n] [/h n] [/o] [/p] [/l] [/swap [path]]
  1867.  
  1868.      where 'myprog' is the main module of the program you are creating. 
  1869.      The options are thus:
  1870.  
  1871.      /s n              n is the size of the stack to allocate (default is
  1872.                        4096).
  1873.  
  1874.      /h n              n is the amount of space to reserve for the heap (in
  1875.                        paragraphs).  The default is all the free memory. 
  1876.  
  1877.      /o                invokes the optimizer.  The optimizer prevents the
  1878.                        output, to the object file, of all the procedures
  1879.                        that are part of included modules but are not
  1880.                        referenced.  This will make your final EXE files
  1881.                        smaller. 
  1882.  
  1883.      /p                tells the linker to include the profiler
  1884.                        (M2Prof.M2O). For further information, see the
  1885.                        chapter on "Utilities".
  1886.  
  1887.      /l                tells the linker to process the line number
  1888.                        information in the .M2O files and include it in the
  1889.                        .DBG file.  This option is disabled if the optimizer
  1890.                        is invoked. 
  1891.  
  1892.      /k                tells the linker to ignore module keys, i.e.  to not
  1893.                        check for module version compatibility.  This option
  1894.                        should be used with extreme care. 
  1895.  
  1896.      /swap [path]      tells the linker to use a swap file.  Code segments
  1897.                        will be kept in this swap file instead of in main
  1898.                        memory during the link process.  This allows you to
  1899.                        link larger programs. 
  1900.  
  1901.      The linker creates two files: the .EXE file is your executable
  1902.      program, the .DBG file is a file containning symbol information for
  1903.      use by other utilities (see Map file generator, Profiler).
  1904.  
  1905.      If the /swap directive is used, a swap file is created.  You may
  1906.      select the path (drive:directory) where the swap file is to be
  1907.      created.  Example:
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.      The Linker                                                          30
  1916.      
  1917.  
  1918.           M2LINK myprog /swap D:
  1919.  
  1920.  
  1921.  
  1922.  
  1923.      6.1 Module keys
  1924.  
  1925.  
  1926.      The module header record and the import records written out by the
  1927.      compiler to the object file are stamped with the date of the .DEF file
  1928.      that was processed - this becomes the module key.  The linker will
  1929.      assure that these module keys in the module header of the imported
  1930.      module and in the import record match; If they do not match, both
  1931.      modules were not compiled using the same definition module. 
  1932.  
  1933.      Because of the use of module keys, it is imperative that the date of
  1934.      the distributed .DEF files not be modified unless you intend to
  1935.      recompile the implementation modules. 
  1936.  
  1937.      
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.      Other utilities                                                     31
  1982.      
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.                                     Chapter 7
  1991.  
  1992.                                  Other utilities
  1993.  
  1994.  
  1995.  
  1996.      
  1997.  
  1998.  
  1999.  
  2000.  
  2001.      7.1 Editor configurator
  2002.  
  2003.  
  2004.      This program lets you define the keystrokes to be used to invoke all
  2005.      the editor commands, the screen attributes (colors) to use, and the
  2006.      default editor options. 
  2007.  
  2008.      Invokation:
  2009.  
  2010.           EDCONFIG
  2011.  
  2012.      EdConfig presents you with a menu from which you may elect to modify
  2013.      the default editor options, the display attributes, or configure the
  2014.      editor commands. 
  2015.  
  2016.      If you are creating a new configuration file, you must configure the
  2017.      editor commands. 
  2018.  
  2019.      If you chose to configure the editor commands, you will be prompted
  2020.      for a log file (default M2ED.HLP), a text file in which all of your
  2021.      command choices will be saved.  You may print this file to create a
  2022.      quick reference card.  EDCONFIG will then prompt you for the key
  2023.      sequence to be used for each editor command.  For each command,
  2024.      EDCONFIG will also give you the option of defining an alternate key
  2025.      sequence. 
  2026.  
  2027.      When you select Quit, the program will prompt you for an output file,
  2028.      the default being 'M2ED.CFG'.
  2029.  
  2030.      
  2031.  
  2032.  
  2033.  
  2034.  
  2035.      7.2 Map file generator
  2036.  
  2037.  
  2038.      Invokation:
  2039.  
  2040.           DBG2MAP program_name
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.      Other utilities                                                     32
  2048.      
  2049.  
  2050.  
  2051.      Reads the .DBG file created by M2LINK and creates a DOS LINK
  2052.      compatible .MAP file. 
  2053.  
  2054.      
  2055.  
  2056.  
  2057.  
  2058.  
  2059.      7.3 Make and the Makefile generator
  2060.  
  2061.  
  2062.      These utilities eliminate the burden, on the user's part, of having to
  2063.      figure out which modules are affected and, therefore, need to be
  2064.      recompiled as a result of any changes to particular definition
  2065.      modules. 
  2066.  
  2067.      GENMAKE creates the .MAK file, the file with all the dependencies
  2068.      (this is the hard part) whereas MAKE (built into the compiler) will
  2069.      insure that these dependencies are observed when updating the object
  2070.      files. 
  2071.  
  2072.      GENMAKE Invokation:
  2073.  
  2074.           GENMAKE main_module_name
  2075.  
  2076.      generates the .MAK file containning all the module dependencies for
  2077.      the named program.  It does this by reading all the IMPORT statements
  2078.      in the main module and, recursively, generating the dependency lists
  2079.      for all those modules (but only the ones that can be found in the
  2080.      current directory!).  GENMAKE will indeed read all the .MOD and .DEF
  2081.      files involved. 
  2082.  
  2083.      MAKE invocation: see "Running the Compiler".
  2084.  
  2085.      MAKE will invoke the compiler as needed to assure that all the
  2086.      dependencies in the make file are observed.  MAKE is dumb in that it
  2087.      will just run through the makefile sequentially.  It was GENMAKE's
  2088.      responsibility to see that the dependencies are listed in a proper
  2089.      sequence.  Please keep this in mind if you should edit a makefile! 
  2090.  
  2091.      
  2092.  
  2093.  
  2094.  
  2095.  
  2096.      7.4 The execution profiler
  2097.  
  2098.  
  2099.      When you link your program with the /p option, the module M2Prof is
  2100.      included in the output generated. 
  2101.  
  2102.      When you execute the program, the profiler will ask you for the name
  2103.      of the .DBG file to use and give you an option of profiling your
  2104.      entire program (generating an execution profile by module), a
  2105.      particular module (generating an execution profile by procedure in
  2106.      that module) or a particular procedure (generating an execution
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.      Other utilities                                                     33
  2114.      
  2115.  
  2116.      profile by line in the procedure). 
  2117.  
  2118.      Upon program termination, the profiler outputs the list of all the
  2119.      modules/procedures/lines profiled, ranked by execution time, to a file
  2120.      of your choice. 
  2121.  
  2122.      This profiler is not that versatile, but it is useful nevertheless. 
  2123.      It proved instrumental in pinpointing some obvious areas for
  2124.      improvement in the compiler (Oh, we did not tell you, did we?  This
  2125.      compiler was written in the language it compiles -- Modula-2 -- and
  2126.      this system was used as our primary development tool since very early
  2127.      in the development process). 
  2128.  
  2129.      
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.      The Library Modules                                                 34
  2180.      
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.                                     Chapter 8
  2189.  
  2190.                                The Library Modules
  2191.  
  2192.  
  2193.  
  2194.      For complete information on what each library module provides, as well
  2195.      as its proper usage, please refer to the .DEF files -- In the next
  2196.      release, we expect to remove the library documentation from the DEF
  2197.      files and place it in a document file that should be more easy to
  2198.      reference. 
  2199.  
  2200.      In addition, the source code of all the library modules is available
  2201.      to all the registered users (see the order form in the back of this
  2202.      document for details). 
  2203.  
  2204.      
  2205.  
  2206.  
  2207.  
  2208.  
  2209.      8.1 Release 1.1 and 1.2 libraries
  2210.  
  2211.  
  2212.      In these releases, several library modules were "extended". We have
  2213.      not created any source level incompatibility with previous library
  2214.      modules, that we are aware of.  But you will have to recompile all
  2215.      your programs, as they will not link with the new library modules. 
  2216.  
  2217.      If upgrading from 1.0, please note that the M2PROCS runtime support
  2218.      module has additional routines and different interfaces for the old
  2219.      ones. 
  2220.  
  2221.      
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.      Shareware                                                           35
  2246.      
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.                                     Chapter 9
  2255.  
  2256.                                     Shareware
  2257.  
  2258.  
  2259.  
  2260.      This software package is distributed as Shareware.
  2261.  
  2262.      Shareware distribution gives users a chance to try this software
  2263.      before buying it.  Besides, by using this distribution method, we
  2264.      eliminate the high cost of publishing and advertising (our users do it
  2265.      for us) and can, therefore, provide the same product for less. 
  2266.  
  2267.      If you try this program and continue to use it, you are expected to
  2268.      register it. 
  2269.  
  2270.      This software can be freely distributed, as long as no money is
  2271.      charged for it, all the files are included, unmodified, and with their
  2272.      modification dates preserved.  If you are going to place this software
  2273.      on a bulletin board (we thank you for it), please upload it in a
  2274.      library format (we suggest ARC) that will preserve this package's
  2275.      integrity. 
  2276.  
  2277.      This software cannot be distributed as a part of, or in conjunction
  2278.      with, another product. 
  2279.  
  2280.      This software cannot be used in a commercial environment without the
  2281.      payment of a $29 (as of this writing) license fee per copy. 
  2282.  
  2283.      Our success will depend not only on the quality of this software but
  2284.      on the willingness of every individual user to "support" its
  2285.      developers. 
  2286.  
  2287.      If you use this product, please send in the registration form in the
  2288.      back of this document, along with your registration fee.  For $39 (as
  2289.      of this writing) we will send you the latest version of this software
  2290.      and all the library and runtime support source code (what a
  2291.      bargain!).  This source code is made available to registered users
  2292.      only! 
  2293.  
  2294.      Whether or not you use this product, please give complete copies of
  2295.      this software to others (the more the better).  You are an integral
  2296.      part of our distribution channel! 
  2297.  
  2298.      
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.      License terms                                                       36
  2312.      
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.                                    Chapter 10
  2321.  
  2322.                                   License terms
  2323.  
  2324.  
  2325.  
  2326.      Before you register this product and become a licensed user, you are
  2327.      granted a limitted license to evaluate the product to determine
  2328.      whether or not it will fit your needs.  Use of this system for any
  2329.      other purpose, before registration and without our written consent, is
  2330.      expressly forbidden. 
  2331.  
  2332.      Registered users are given a non-exclusive license to use this
  2333.      software on any machine that they have access to, but not on more than
  2334.      one at a time (the "treat this software like a book" idea). 
  2335.  
  2336.      Registered users may modify the source code provided to suit their
  2337.      needs, but this source code (in original or modified form) may not be
  2338.      distributed without the prior written consent of Fitted Software
  2339.      Tools.
  2340.  
  2341.      Registered users may include compiled portions of the library and
  2342.      runtime support code in the programs by them developed, and use or
  2343.      distribute these programs without payment of any additional license
  2344.      fees to Fitted Software Tools.
  2345.  
  2346.      
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.      Support                                                             37
  2378.      
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.                                    Chapter 11
  2387.  
  2388.                                      Support
  2389.  
  2390.  
  2391.  
  2392.      Our basic philosophy is very simple: Without happy users, we do not
  2393.      have a business -- or, at least, we will not have one for long! 
  2394.  
  2395.      We will do everything in our power to assure that our users get the
  2396.      kind of support that they deserve and we can afford to provide. 
  2397.  
  2398.      Above all, we do not want to create false expectations on the part of
  2399.      our users, the reason for this chapter. 
  2400.  
  2401.      We will provide our registered users with support either by mail
  2402.      through BIX (conference 'fst'), or through our BBS, at 404/497-0931.
  2403.  
  2404.      The advantages of using the BBS or BIX are: all users get immediate
  2405.      notification of bugs and fixes; It encourages users to participate in
  2406.      finding resolution to "how to" type questions. 
  2407.  
  2408.      We cannot, of course, promise to fix any bug that you may find within
  2409.      a certain period of time.  As a matter of fact, we do not even promise
  2410.      to fix any and all bugs that you may find, but we will try...  When a
  2411.      fix is not imminent, we will try to give you a workaround procedure,
  2412.      so that you may go on with your work. 
  2413.  
  2414.      As we fix bugs, we will make the new versions of the affected programs
  2415.      available for download from the BBS (we plan on implementing something
  2416.      similar on BIX, as soon as conference private listings areas are made
  2417.      available).  Should this not be acceptable to you, you may elect to
  2418.      have the fixes mailed to you, for $5 to cover media and handling
  2419.      charges. 
  2420.  
  2421.      We will also make all new product updates available for download off
  2422.      the BBS.
  2423.  
  2424.      In those cases where a reported bug gets fixed only in a later release
  2425.      of the product, the first user reporting the bug has the option of
  2426.      getting that update by mail for the $5 that we charge to ship bug
  2427.      fixes. 
  2428.  
  2429.      Registered users have the option of getting software updates by mail
  2430.      instead of downloading them.  The current price of such updates is
  2431.      $12.
  2432.  
  2433.      
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.      Your input matters to us                                            38
  2444.      
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.                                    Chapter 12
  2453.  
  2454.                             Your input matters to us
  2455.  
  2456.  
  2457.  
  2458.      You can bet that this is serious!  We know, and you know, that there
  2459.      are many ways in which this system can be improved.  It is in our
  2460.      common interest that we agree on just how (what needs changing, what
  2461.      additional capabilities are needed) and when (let's take care of the
  2462.      more important stuff first!). 
  2463.  
  2464.      Maybe you like this software so much that you would hate to see us
  2465.      improve it in the wrong direction (ha, ha, ha)... 
  2466.  
  2467.      Maybe you find some weaknesses in this product that make it awkward to
  2468.      use. 
  2469.  
  2470.      Maybe even (God forbid!)  that one or more of those weaknesses make
  2471.      this software unusable for your purposes. 
  2472.  
  2473.      Whichever the case may be, we need to know about it, our future is at
  2474.      stake!!! 
  2475.  
  2476.      So, please!, fill out the survey form and send it in. 
  2477.  
  2478.      
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.                        Your comments would be appreciated
  2512.  
  2513.      
  2514.  
  2515.  
  2516.  
  2517.      How did you first learn about this product?
  2518.  
  2519.           ---------------------------------------------------------
  2520.  
  2521.      Where did you get this software from?
  2522.  
  2523.           ( ) us                   ( ) a bulletin board
  2524.           ( ) a friend                 phone # ___ ___ ____
  2525.           ( ) a computer club      ( ) a shareware software distributor
  2526.           ( ) other ________________________
  2527.  
  2528.      Systems you intend to use this software on
  2529.  
  2530.           ( ) PC (8088/8086)       ( ) AT (80286)      ( ) 80386
  2531.  
  2532.      Typical system's configuration
  2533.  
  2534.           ( ) hard disk
  2535.           ( ) 512k       ( ) 640k
  2536.           ( ) extended memory
  2537.           ( ) expanded memory (EMS, EEMS)
  2538.           ( ) EGA adapter
  2539.           ( ) VGA adapter
  2540.  
  2541.      What programming languages do you use regularly?
  2542.  
  2543.           ---------------------------------------------------------
  2544.  
  2545.      What do you like the most about this system?
  2546.  
  2547.           _____________________________________________________________
  2548.           _____________________________________________________________
  2549.           _____________________________________________________________
  2550.           _____________________________________________________________
  2551.           _____________________________________________________________
  2552.  
  2553.      What do you NOT like about this system?
  2554.  
  2555.           _____________________________________________________________
  2556.           _____________________________________________________________
  2557.           _____________________________________________________________
  2558.           _____________________________________________________________
  2559.           _____________________________________________________________
  2560.  
  2561.      Other comments / suggestions:
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.                                    BUG REPORT
  2578.  
  2579.      We would like to think that our software is bug free, but we have been
  2580.      around a while.  Someone once wrote that a bug free program is a
  2581.      program whose bugs have not been uncovered yet. 
  2582.  
  2583.      So, if you uncover one of those nasty critters, please provide us with
  2584.      the information below, and whatever else that may help us duplicate
  2585.      the problem. 
  2586.  
  2587.  
  2588.      Name_____________________________________________
  2589.  
  2590.      Company__________________________________________
  2591.  
  2592.      Address__________________________________________
  2593.  
  2594.      City, State, Zip_________________________________
  2595.  
  2596.      Telephone _____________
  2597.  
  2598.  
  2599.      Version of the software in use:  ___________________________
  2600.  
  2601.      Machine in use (make and model): ___________________________
  2602.  
  2603.      Memory / Disks / Display type:   ___________________________
  2604.  
  2605.      Operating system used:           ___________________________
  2606.  
  2607.      Other system information that may be pertinent (PATH settings,
  2608.      CONFIG.SYS contents,...) 
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.      Problem description:
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.                                    ORDER FORM
  2644.  
  2645.  
  2646.  
  2647.  
  2648.      Mail this form to:
  2649.  
  2650.           Fitted Software Tools
  2651.           P.O.Box 867403
  2652.           Plano, TX 75086
  2653.  
  2654.      to register your copy/copies of the Modula-2 compiler, register/order
  2655.      additional copies, and/or order updates. 
  2656.  
  2657.      We distribute the software and documentation on 360k floppies.  A
  2658.      printed version of the manual is not available yet. 
  2659.  
  2660.      The unauthorized distribution of the library and runtime support
  2661.      source code included in the distribution disks that you receive when
  2662.      you order a registered copy or update is specifically prohibited. 
  2663.      This source code is made available to registered users only. 
  2664.  
  2665.      If you are ordering multiple copies for your organization (or for you
  2666.      and your friends), we would suggest that you order 1 of the $39
  2667.      packages and the rest as $29 registrations.  You may then distribute
  2668.      the number of copies that you ordered from the master that you
  2669.      receive. 
  2670.  
  2671.  
  2672.      Name_____________________________________________
  2673.  
  2674.      Company__________________________________________
  2675.  
  2676.      Address__________________________________________
  2677.  
  2678.      City, State, Zip_________________________________
  2679.  
  2680.  
  2681.      QTY
  2682.      ___   X   Registration @ $29.00                      _________
  2683.  
  2684.      ___   X   Registration & latest version @ $39.00     _________
  2685.  
  2686.      ___   X   floppy updates @ $12.00                    _________
  2687.  
  2688.                Sales tax (TX residents)                   _________
  2689.  
  2690.      Total enclosed:                                      _________
  2691.  
  2692.  
  2693.      If ordering the latest version, please specify how long you are
  2694.      willing to wait for a new, if imminent, update _________________
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.                            Table of Contents
  2713.  
  2714.  
  2715.      Chapter 1 Introduction                                           2
  2716.  
  2717.         1.1 Hardware requirements                                     3
  2718.         1.2 Software requirements                                     3
  2719.         1.3 Version 1.3                                               3
  2720.         1.4 About version 1.2                                         3
  2721.         1.5 What was new in version 1.1                               4
  2722.         1.6 As version 1.1 becomes history...                         5
  2723.  
  2724.      Chapter 2 Software installation                                  6
  2725.  
  2726.         2.1 Theory                                                    6
  2727.         2.2 Recommended setup for a system with 2 floppy drives
  2728.                                                                       7
  2729.         2.3 Recommended setup for a hard disk system                  8
  2730.  
  2731.      Chapter 3 A little tour through the system                       9
  2732.  
  2733.         3.1 The tour                                                  9
  2734.  
  2735.      Chapter 4 The Compiler                                           12
  2736.  
  2737.         4.1 Running the integrated compiler: MC                       13
  2738.         4.2 Running the freestanding compiler: M2COMP                 14
  2739.         4.3 The compilation process                                   14
  2740.  
  2741.               4.3.0.1 The input file                                  14
  2742.               4.3.0.2 The imported modules                            15
  2743.               4.3.0.3 The output file                                 15
  2744.               4.3.0.4 A warning                                       15
  2745.  
  2746.         4.4 Compiler directives                                       16
  2747.         4.5 Runtime errors                                            16
  2748.  
  2749.            4.5.1 Trapping runtime errors in your program              17
  2750.  
  2751.         4.6 Compiler size limits                                      17
  2752.         4.7 The language supported                                    18
  2753.  
  2754.            4.7.1 LONGINT and LONGCARD                                 18
  2755.            4.7.2 Additional standard procedures                       19
  2756.  
  2757.               4.7.2.1 NEW and DISPOSE                                 19
  2758.               4.7.2.2 LONG and SHORT                                  19
  2759.  
  2760.         4.8 Objects exported by the pseudo module SYSTEM              19
  2761.  
  2762.               4.8.0.1 TYPE BYTE                                       20
  2763.               4.8.0.2 TYPE WORD                                       20
  2764.               4.8.0.3 TYPE ADDRESS                                    20
  2765.               4.8.0.4 SEG and OFS                                     20
  2766.               4.8.0.5 PROCEDURE ADR                                   21
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.               4.8.0.6 PROCEDURE FLAT                                  21
  2775.               4.8.0.7 PROCEDURE PTR                                   21
  2776.               4.8.0.8 PROCEDURE SEGMENT                               21
  2777.               4.8.0.9 PROCEDURE OFFSET                                21
  2778.               4.8.0.10 PROCEDURE NEWPROCESS                           21
  2779.               4.8.0.11 PROCEDURE TRANSFER                             21
  2780.               4.8.0.12 PROCEDURE IOTRANSFER                           22
  2781.               4.8.0.13 ASSEMBLER                                      22
  2782.  
  2783.         4.9 The generated object code                                 23
  2784.  
  2785.            4.9.1 Data type representation                             23
  2786.            4.9.2 The runtime memory map                               24
  2787.            4.9.3 Procedure calling conventions                        25
  2788.  
  2789.               4.9.3.1 Parameter passing (all except open array
  2790.                     parameters)                                       25
  2791.               4.9.3.2 Parameter passing (open array parameters)
  2792.                                                                       25
  2793.               4.9.3.3 Returning values from a function procedure
  2794.                                                                       25
  2795.  
  2796.         4.10 Module priorities                                        25
  2797.         4.11 Memory models                                            26
  2798.  
  2799.      Chapter 5 The Text Editor                                        27
  2800.  
  2801.      Chapter 6 The Linker                                             29
  2802.  
  2803.         6.1 Module keys                                               30
  2804.  
  2805.      Chapter 7 Other utilities                                        31
  2806.  
  2807.         7.1 Editor configurator                                       31
  2808.         7.2 Map file generator                                        31
  2809.         7.3 Make and the Makefile generator                           32
  2810.         7.4 The execution profiler                                    32
  2811.  
  2812.      Chapter 8 The Library Modules                                    34
  2813.  
  2814.         8.1 Release 1.1 and 1.2 libraries                             34
  2815.  
  2816.      Chapter 9 Shareware                                              35
  2817.  
  2818.      Chapter 10 License terms                                         36
  2819.  
  2820.      Chapter 11 Support                                               37
  2821.  
  2822.      Chapter 12 Your input matters to us                              38
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.